<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>tests/src/vfs/extfs/helpers-list/README</title>
<meta name='robots' content='noindex,nofollow' />
<meta name='generator' content='GLOBAL-6.5.7' />
<meta http-equiv='Content-Style-Type' content='text/css' />
<link rel='stylesheet' type='text/css' href='../style.css' />
</head>
<body>
<!-- beginning of fixed guide -->
<div id='guide'><ul>
<li><a href='#TOP'><img class='icon' src='../icons/first.png' alt='[^]' /></a></li>
<li><a href='#BOTTOM'><img class='icon' src='../icons/last.png' alt='[v]' /></a></li>
<li><a href='#TOP'><img class='icon' src='../icons/top.png' alt='[top]' /></a></li>
<li><a href='#BOTTOM'><img class='icon' src='../icons/bottom.png' alt='[bottom]' /></a></li>
<li><a href='../mains.html'><img class='icon' src='../icons/index.png' alt='[index]' /></a></li>
<li><a href='../help.html'><img class='icon' src='../icons/help.png' alt='[help]' /></a></li>
<li class='standout'><span><a href='../files/tests.html'>tests</a>/<a href='../files/tests--src.html'>src</a>/<a href='../files/tests--src--vfs.html'>vfs</a>/<a href='../files/tests--src--vfs--extfs.html'>extfs</a>/<a href='../files/tests--src--vfs--extfs--helpers-list.html'>helpers-list</a>/README</span></li>
</ul></div>
<!-- end of fixed guide -->
<a id='TOP' name='TOP'></a><h2 class='header'><a href='../mains.html'>root</a>/<a href='../files/tests.html'>tests</a>/<a href='../files/tests--src.html'>src</a>/<a href='../files/tests--src--vfs.html'>vfs</a>/<a href='../files/tests--src--vfs--extfs.html'>extfs</a>/<a href='../files/tests--src--vfs--extfs--helpers-list.html'>helpers-list</a>/README</h2>
<em class='comment'>/* <img class='icon' src='../icons/n_left.png' alt='[previous]' /><img class='icon' src='../icons/n_right.png' alt='[next]' /><img class='icon' src='../icons/n_first.png' alt='[first]' /><img class='icon' src='../icons/n_last.png' alt='[last]' /><img class='icon' src='../icons/n_top.png' alt='[top]' /><a href='#BOTTOM'><img class='icon' src='../icons/bottom.png' alt='[bottom]' /></a><a href='../mains.html'><img class='icon' src='../icons/index.png' alt='[index]' /></a><a href='../help.html'><img class='icon' src='../icons/help.png' alt='[help]' /></a>&nbsp;<input type='text' readonly onfocus='this.select();' value='+1 tests/src/vfs/extfs/helpers-list/README'  /> */</em>
<hr />
<pre>
<a id='L1' name='L1'></a>---
<a id='L2' name='L2'></a>title: A tester for extfs helpers
<a id='L3' name='L3'></a>...
<a id='L4' name='L4'></a> 
<a id='L5' name='L5'></a>Guide
<a id='L6' name='L6'></a>=====
<a id='L7' name='L7'></a> 
<a id='L8' name='L8'></a>Introduction
<a id='L9' name='L9'></a>------------
<a id='L10' name='L10'></a> 
<a id='L11' name='L11'></a>The extfs filesystem is composed of various helpers (uzip, urar, uarc,
<a id='L12' name='L12'></a>...). One command every helper must answer to is "list", to list the
<a id='L13' name='L13'></a>files on its filesystem.
<a id='L14' name='L14'></a> 
<a id='L15' name='L15'></a>The purpose of this tester is to test this "list" facet of every helper
<a id='L16' name='L16'></a>to ensure that it indeed works, at present, and that we won't
<a id='L17' name='L17'></a>inadvertently break it, in the future, as we modify its code or MC's
<a id='L18' name='L18'></a>code.
<a id='L19' name='L19'></a> 
<a id='L20' name='L20'></a>Key concept: Inputs
<a id='L21' name='L21'></a>-------------------
<a id='L22' name='L22'></a> 
<a id='L23' name='L23'></a>Most helpers work by parsing the output of some 3'rd party software.
<a id='L24' name='L24'></a>Which for them becomes the *input*. Helpers sometimes support **several
<a id='L25' name='L25'></a>variations** of such input. E.g., the uzip helper supports three
<a id='L26' name='L26'></a>variations.
<a id='L27' name='L27'></a> 
<a id='L28' name='L28'></a>The tester keeps a repository, in the data folder, of the various inputs
<a id='L29' name='L29'></a>each helper proclaims to support. Each input is stored in a file with an
<a id='L30' name='L30'></a>`.input` suffix.
<a id='L31' name='L31'></a> 
<a id='L32' name='L32'></a>Key concept: Outputs
<a id='L33' name='L33'></a>--------------------
<a id='L34' name='L34'></a> 
<a id='L35' name='L35'></a>Along with each input file, the data folder also holds the output the
<a id='L36' name='L36'></a>helper is expected to produce given the corresponding input. Each output
<a id='L37' name='L37'></a>is stored in a file with an `.output` suffix.
<a id='L38' name='L38'></a> 
<a id='L39' name='L39'></a>We call this output "the expected output".
<a id='L40' name='L40'></a> 
<a id='L41' name='L41'></a>Incidentally, an `.output` file stores not the _raw_ output of the helper
<a id='L42' name='L42'></a>but its output _after parsing_. In other words, what's stored is the
<a id='L43' name='L43'></a>unambiguous _meaning_ of the helper's output. This means that as long as
<a id='L44' name='L44'></a>the helper's code isn't modified in a way that changes the meaning of its
<a id='L45' name='L45'></a>output, the `.output` file remains up-to-date.
<a id='L46' name='L46'></a> 
<a id='L47' name='L47'></a>How the tester works
<a id='L48' name='L48'></a>--------------------
<a id='L49' name='L49'></a> 
<a id='L50' name='L50'></a>The tester feeds each helper its prepared inputs and reads back the
<a id='L51' name='L51'></a>helper's "list" answer -- the helper's **output**. This output is a list
<a id='L52' name='L52'></a>of files in a format similar to `ls -l`, which MC is able to parse. The
<a id='L53' name='L53'></a>tester checks that this output parses without errors (errors are, for
<a id='L54' name='L54'></a>example, dates in unsupported format). It then compares this parsed
<a id='L55' name='L55'></a>output (which we call "the actual output") with a previously saved copy
<a id='L56' name='L56'></a>of this output which is known to be correct (and which we call "the
<a id='L57' name='L57'></a>expected output", mentioned in the previous section). This previously
<a id='L58' name='L58'></a>stored output too is in the data folder, in files with `.output` suffix.
<a id='L59' name='L59'></a> 
<a id='L60' name='L60'></a>If there's any discrepancy between the *actual output* and the
<a id='L61' name='L61'></a>*expected output*, the test fails.
<a id='L62' name='L62'></a> 
<a id='L63' name='L63'></a>Running the tester
<a id='L64' name='L64'></a>------------------
<a id='L65' name='L65'></a> 
<a id='L66' name='L66'></a>You can run the tester with `make check`.
<a id='L67' name='L67'></a> 
<a id='L68' name='L68'></a>But you'll find it more appealing to run the tester with the `run`
<a id='L69' name='L69'></a>script. You'll get a colorful description of what's going on.
<a id='L70' name='L70'></a> 
<a id='L71' name='L71'></a>(`run` is created by running `make check` for the 1st time, in the build
<a id='L72' name='L72'></a>tree.)
<a id='L73' name='L73'></a> 
<a id='L74' name='L74'></a>Reference
<a id='L75' name='L75'></a>=========
<a id='L76' name='L76'></a> 
<a id='L77' name='L77'></a>The data folder
<a id='L78' name='L78'></a>---------------
<a id='L79' name='L79'></a> 
<a id='L80' name='L80'></a>There are several types of files in the data folder:
<a id='L81' name='L81'></a> 
<a id='L82' name='L82'></a>### Input file ###
<a id='L83' name='L83'></a> 
<a id='L84' name='L84'></a>An input file is named:
<a id='L85' name='L85'></a> 
<a id='L86' name='L86'></a>&gt; `&lt;helper-name&gt;[.optional-embedded-description].input`
<a id='L87' name='L87'></a> 
<a id='L88' name='L88'></a>You create such files simply by redirecting the 3'rd party software's
<a id='L89' name='L89'></a>output to a file.
<a id='L90' name='L90'></a> 
<a id='L91' name='L91'></a>### Output file ###
<a id='L92' name='L92'></a> 
<a id='L93' name='L93'></a>This file is named the same as the corresponding input file but with an
<a id='L94' name='L94'></a>`.output` suffix.
<a id='L95' name='L95'></a> 
<a id='L96' name='L96'></a>The easiest way to create these files is by invoking the `run` script
<a id='L97' name='L97'></a>with the `--create-output` option.
<a id='L98' name='L98'></a> 
<a id='L99' name='L99'></a>### Environment file ###
<a id='L100' name='L100'></a> 
<a id='L101' name='L101'></a>Optional. This file defines environment variables the helper may use to
<a id='L102' name='L102'></a>determine the variant of the input. This file is named the same as the
<a id='L103' name='L103'></a>corresponding input file but with an `.env_var` suffix.
<a id='L104' name='L104'></a> 
<a id='L105' name='L105'></a>### Arguments file ###
<a id='L106' name='L106'></a> 
<a id='L107' name='L107'></a>Optional. This file defines extra command-line options to pass to the
<a id='L108' name='L108'></a>[parser](#mc_parse_ls_l). This file is named the same as the
<a id='L109' name='L109'></a>corresponding input file but with an `.args` suffix.
<a id='L110' name='L110'></a> 
<a id='L111' name='L111'></a>The contents of an output file must be the same no matter on what
<a id='L112' name='L112'></a>computer and at what time we generate it. Therefore we need to tell the
<a id='L113' name='L113'></a>parser to drop any non-fixed elements in that file. E.g., if the dates
<a id='L114' name='L114'></a>used are relative (as is the case for the default `ls` dates), we need to
<a id='L115' name='L115'></a>drop them with `--drop-mtime`. Similarly, if a helper returns user and
<a id='L116' name='L116'></a>group _names_ that are different than the running user's, they must be
<a id='L117' name='L117'></a>dropped with `--drop-ids`.
<a id='L118' name='L118'></a> 
<a id='L119' name='L119'></a>### Other files ###
<a id='L120' name='L120'></a> 
<a id='L121' name='L121'></a>Any other file is ignored by the tester.
<a id='L122' name='L122'></a> 
<a id='L123' name='L123'></a>mc_parse_ls_l
<a id='L124' name='L124'></a>-------------
<a id='L125' name='L125'></a> 
<a id='L126' name='L126'></a>This program (built with `make check`) is at the heart of the tester
<a id='L127' name='L127'></a>mechanism. It parses a list of files, in a format similar to `ls -l`,
<a id='L128' name='L128'></a>just as MC would. This program is used to parse (and thereby verify) the
<a id='L129' name='L129'></a>output of the helpers. _You don't need to invoke it yourself;_ but, for
<a id='L130' name='L130'></a>educational purpose, here are a few examples:
<a id='L131' name='L131'></a> 
<a id='L132' name='L132'></a>    $ LC_ALL=C ls -l | ./mc_parse_ls_l
<a id='L133' name='L133'></a> 
<a id='L134' name='L134'></a>    $ LC_ALL=C ls -l | ./mc_parse_ls_l --symbolic-ids
<a id='L135' name='L135'></a> 
<a id='L136' name='L136'></a>    $ LC_ALL=C ls -l | ./mc_parse_ls_l --output-format yaml
<a id='L137' name='L137'></a> 
<a id='L138' name='L138'></a>test_all
<a id='L139' name='L139'></a>--------
<a id='L140' name='L140'></a> 
<a id='L141' name='L141'></a>This is the tester itself. You invoke it with `make check`, or with the
<a id='L142' name='L142'></a>`run` script. Invoking it directly is a bit involving because you need to
<a id='L143' name='L143'></a>provide it with 2 or 3 directory paths. `run` does this work for you.
<a id='L144' name='L144'></a> 
<a id='L145' name='L145'></a>Environment variables
<a id='L146' name='L146'></a>---------------------
<a id='L147' name='L147'></a> 
<a id='L148' name='L148'></a>### Frequently used variables ###
<a id='L149' name='L149'></a> 
<a id='L150' name='L150'></a>#### MC_TEST_EXTFS_LIST_CMD ####
<a id='L151' name='L151'></a> 
<a id='L152' name='L152'></a>When a helper runs under the tester, the environment variable
<a id='L153' name='L153'></a>`MC_TEST_EXTFS_LIST_CMD` holds the command that's to provide input. The
<a id='L154' name='L154'></a>helper's source code must be modified to use this command instead of the
<a id='L155' name='L155'></a>command it usually uses. This is the device which lets us plug our own
<a id='L156' name='L156'></a>input into the helper and *without which a helper can't be tested!*
<a id='L157' name='L157'></a> 
<a id='L158' name='L158'></a>Let's have a little example. The uzoo helper originally has:
<a id='L159' name='L159'></a> 
<a id='L160' name='L160'></a>    ZOO=zoo
<a id='L161' name='L161'></a>    ...
<a id='L162' name='L162'></a>    mczoofs_list () {
<a id='L163' name='L163'></a>      $ZOO lq "$ARCHIVE" | mawk '......'
<a id='L164' name='L164'></a>    }
<a id='L165' name='L165'></a>    ...
<a id='L166' name='L166'></a> 
<a id='L167' name='L167'></a>To make this helper testable, we need to change the first line to:
<a id='L168' name='L168'></a> 
<a id='L169' name='L169'></a>    ZOO=${MC_TEST_EXTFS_LIST_CMD:-zoo}
<a id='L170' name='L170'></a> 
<a id='L171' name='L171'></a>(or equivalent.)
<a id='L172' name='L172'></a> 
<a id='L173' name='L173'></a>The command in `MC_TEST_EXTFS_LIST_CMD` is a black-box for the helper,
<a id='L174' name='L174'></a>and it intentionally ignores any arguments passed to it (so that `lq
<a id='L175' name='L175'></a>"$ARCHIVE"`, above, won't cause problems).
<a id='L176' name='L176'></a> 
<a id='L177' name='L177'></a>### Infrequently used variables ###
<a id='L178' name='L178'></a> 
<a id='L179' name='L179'></a>#### MC_TEST_EXTFS_INPUT ####
<a id='L180' name='L180'></a> 
<a id='L181' name='L181'></a>Contains the path of the [input file]. You'll more commonly use
<a id='L182' name='L182'></a>[MC_TEST_EXTFS_LIST_CMD], though.
<a id='L183' name='L183'></a> 
<a id='L184' name='L184'></a>#### MC_TEST_EXTFS_DATA_DIR ####
<a id='L185' name='L185'></a> 
<a id='L186' name='L186'></a>Contains the path of [the data folder]. Use it when you need to
<a id='L187' name='L187'></a>construct the paths of other files you store there.
<a id='L188' name='L188'></a> 
<a id='L189' name='L189'></a>#### MC_TEST_EXTFS_DATA_BUILD_DIR ####
<a id='L190' name='L190'></a> 
<a id='L191' name='L191'></a>Contains the path of [the data folder], but in the *build* tree. This is
<a id='L192' name='L192'></a>where *.in files from the source tree end up. If you don't know what
<a id='L193' name='L193'></a>these are, you can safely ignore this variable.
<a id='L194' name='L194'></a> 
<a id='L195' name='L195'></a>#### MC_TEST_EXTFS_CONFIG_SH ####
<a id='L196' name='L196'></a> 
<a id='L197' name='L197'></a>Contains the path of *config.sh*, a file you can "source" into shell
<a id='L198' name='L198'></a>scripts (including the [environment file]) to gain access to values set
<a id='L199' name='L199'></a>when Midnight Commander was compiled. Example:
<a id='L200' name='L200'></a> 
<a id='L201' name='L201'></a>    . "$MC_TEST_EXTFS_CONFIG_SH"
<a id='L202' name='L202'></a>    $PERL -e 'print "hello"'
<a id='L203' name='L203'></a> 
<a id='L204' name='L204'></a>Currently, this variable is equal to
<a id='L205' name='L205'></a>"[$MC_TEST_EXTFS_DATA_BUILD_DIR][MC_TEST_EXTFS_DATA_BUILD_DIR]/config.sh",
<a id='L206' name='L206'></a>but you're advised to use only `$MC_TEST_EXTFS_CONFIG_SH` as we may
<a id='L207' name='L207'></a>change this file's location in the future.
</pre>
<hr />
<a id='BOTTOM' name='BOTTOM'></a>
<em class='comment'>/* <img class='icon' src='../icons/n_left.png' alt='[previous]' /><img class='icon' src='../icons/n_right.png' alt='[next]' /><img class='icon' src='../icons/n_first.png' alt='[first]' /><img class='icon' src='../icons/n_last.png' alt='[last]' /><a href='#TOP'><img class='icon' src='../icons/top.png' alt='[top]' /></a><img class='icon' src='../icons/n_bottom.png' alt='[bottom]' /><a href='../mains.html'><img class='icon' src='../icons/index.png' alt='[index]' /></a><a href='../help.html'><img class='icon' src='../icons/help.png' alt='[help]' /></a>&nbsp;<input type='text' readonly onfocus='this.select();' value='+207 tests/src/vfs/extfs/helpers-list/README'  /> */</em>
</body>
</html>
